Support for explicit public API markers #116

KirpichenkovPavel · 2023-01-11T17:27:53Z

The pull request introduces support for two new features:

Explicit public markers. Existing properties ignoredProjects, ignoredPackages and nonPublicMarkers allow excluding some parts of API from compatibility validation and checking the rest. New publicMarkers, publicPackages and publicClasses do the opposite: if any of them is used, only explicitly marked declarations are considered for validation, all the rest are excluded.
Adding extra Gradle source sets to check for Kotlin-JVM project. Without this change only the main source set can be validated.

Motivation

In kotlin.git we would like to maintain binary compatibility only for a few parts of the :kotlin-gradle-plugin project related to the External Kotlin Target API, that will be used by third parties when implemented. The declarations are either annotated, or belong to a specific package. Use of the existing API of validator to exclude everything else is not very convenient and would complicate maintenance of the project in the future. Because, for instance, adding new packages would require build script changes, as they have to be excluded from validation. Parts of the relevant code belong to a custom Gradle source set, so without the second introduced feature validation is not possible.

Implementation notes

Explicit marker mode only affects validation if any of the new public* properties are used in a build script, which shouldn't affect any users that don't touch the properties
Explicit declaration filtering happens before the usual filtering of ignored projects, packages and marked non-public declarations. This makes it possible to combine two modes, e.g. filter out marked non-public members of a class from a public package
In case of clashes, when the same declaration is both ignored and explicitly public at the same time, ignored "wins"
Listing extra source sets for validation is only supported for projects with the kotlin-jvm Gradle plugin to minimize the changes

If the added properties are used, all unmatched declarations will be excluded from the API check. If properties for both ignored and explicit markers are set, filtering of ignored declarations will happen after filtering of declarations not explicitly marked as public.

qwwdfsad · 2023-02-21T17:58:49Z

src/main/kotlin/api/KotlinSignaturesLoading.kt

        .map { it.flattenNonPublicBases() }
        .filterNot { it.isNotUsedWhenEmpty && it.memberSignatures.isEmpty() }
 }

+@ExternalApi
+public fun List<ClassBinarySignature>.retainExplicitlyIncludedIfDeclared(


Could you please elaborate on whether you do plan to use retainExplicitlyIncludedIfDeclared exclusively or also plugin DSL to use the API?

qwwdfsad

Nicely done!

* Add support for defining public declarations explicitly If the added properties are used, all unmatched declarations will be excluded from the API check. If properties for both ignored and explicit markers are set, filtering of ignored declarations will happen after filtering of declarations not explicitly marked as public. * Support validation of non-main source sets for kotlin-jvm projects Pull request Kotlin/binary-compatibility-validator#116

* Add support for defining public declarations explicitly If the added properties are used, all unmatched declarations will be excluded from the API check. If properties for both ignored and explicit markers are set, filtering of ignored declarations will happen after filtering of declarations not explicitly marked as public. * Support validation of non-main source sets for kotlin-jvm projects Pull request Kotlin/binary-compatibility-validator#116 Moved from Kotlin/binary-compatibility-validator@5d08f51

KirpichenkovPavel added 2 commits December 27, 2022 13:05

Support validation of non-main source sets for kotlin-jvm projects

5d3f4b7

KirpichenkovPavel requested a review from qwwdfsad January 11, 2023 17:27

qwwdfsad reviewed Feb 21, 2023

View reviewed changes

qwwdfsad self-requested a review March 3, 2023 13:37

qwwdfsad approved these changes Mar 3, 2023

View reviewed changes

qwwdfsad merged commit 5d08f51 into master Mar 3, 2023

qwwdfsad deleted the pk/public-markers branch March 3, 2023 13:43

tso mentioned this pull request Apr 6, 2023

Add support for checking/generating API of testFixtures #117

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Support for explicit public API markers #116

Support for explicit public API markers #116

Uh oh!

KirpichenkovPavel commented Jan 11, 2023

Uh oh!

qwwdfsad Feb 21, 2023 •

edited

Loading

Uh oh!

qwwdfsad left a comment

Uh oh!

Uh oh!

Support for explicit public API markers #116

Support for explicit public API markers #116

Uh oh!

Conversation

KirpichenkovPavel commented Jan 11, 2023

Motivation

Implementation notes

Uh oh!

qwwdfsad Feb 21, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qwwdfsad left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

qwwdfsad Feb 21, 2023 •

edited

Loading